Developer CD Series 1996 April: Mac OS SDK/Dev.CD Apr 96 SDK/Dev.CD Apr 96 SDK1.toast/Development Kits (Disc 1)/OpenDoc/Documentation/Tech Notes & Articles/Recipes/Part Persistency/Part Init & Externalizing

Text File | 1995-07-11 | 5.0 KB | 175 lines | [TEXT/ttxt]

OpenDoc™ Recipes


Part Init & Externalizing recipe
By The OpenDoc Design Team
July 11th, 1995


© 1993-1995  Apple Computer, Inc. All Rights Reserved.
Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.


Introduction

This document contains some sample code showing how a Part Editor externalizes and internalizes itself.

The sample code shown here is for a very simple Part Editor. Its assumptions may not be valid for a Part Editor with more functionality:

•fPartData is a Pascal string (Str255) which holds the Part Content or Part Data.
•The sample code reads and writes the entire Part Data from and to persistent storage.
•The sample code uses a fDirty flag which it sets to true when its contents change.
•The sample code uses a fSelf field to hang onto the partwrapper object.

Proper treatment of permissions

•Note that the part is responsible for caching the draft permissions in InitPartFromStorage.  The sample code does this by assigning a field
fPermissions = storageUnit->GetDraft(ev)->GetPermissions(ev);
in the  InitPartFromStorage.  Whenever the potential for changing user content exists, the part should check to make sure
fPermissions >= kDPSharedWrite
before changing any of the content.  Also, as a side effect, if fPermissions < kDPSharedWrite then fDirty should never be able to become kODTrue, and as a result, the Externalize method will never write to the contents property.


PartWrapper

In addition to a Storage Unit, InitPart and InitPartFromStorage methods on ODPart also takes an extra parameter partWrapper.   The partWrapper parameter represents a delegator object which OpenDoc uses to insulate the rest of OpenDoc from having to have a direct pointer to your ODPart object.  This feature helps implement features such as being able to change the editor of part without closing and reopening the document.  Plus, it makes an excellent bottleneck for platform developers.  For the most part, all the partWrapper does is delegate methods of the part API to your ODPart object.

The Part Editor must save this parameter in the Part's internal field; you'll see this in the sample code below. Whenever an OpenDoc API requires the Part Editor to pass in an ODPart* representing the Part, instead of passing in somSelf, the Part Editor MUST pass in partWrapper stored in the Part's internal field.  An example is when registering the Part for idle time.  A Part Editor should NEVER pass somSelf in as a parameter to an OpenDoc API call.

Sample Code for Initialization

// includes the appropriate .xh files from OpenDoc

#include "StorageU.xh"

#include "StdProps.xh"

#include "POUtils.h"


…

// Define the Part Kind.
//
// This should probably be in your part's …def.h file which should be #included
// in your .r file for your 'nmap' resources

#define kMyPartKind    "Sample:Kind:CMyKind"

...
void    MyPartInitPart(MyPart* somSelf,
                                    Enviornment* ev,
                                    ODStorageUnit* storageUnit,
                                    ODPart* partWrapper)
{

    ...

    // Call your parent's init routine

    parent_InitPart(somSelf, ev, storageUnit, partWrapper);

 // set your dirty flag

 fDirty = kODTrue;

    // save off the partwrapper object

    fSelf = partWrapper;

}

void    MyPartInitPartFromStorage(MyPart* somSelf,
                                    Environment* ev,
                                    ODStorageUnit* storageUnit,
                                    ODPartWrapper* partWrapper)

{

    // Initialize the parent.

    parent_InitPartFromStorage(somSelf, ev, storageUnit, partWrapper);

    // Focus to the value where the Part Data is stored.

    storageUnit->Focus(ev,
                        kODPropContents,
                        kODPosUndefined,
                        kMyPartKind,
                        0,
                        kODPosUndefined);

    // Get the size of the string.

    fPartData[0] = storageUnit->GetSize(ev);

    // Get the string itself

    storageUnit->GetValue(fPartData[0],&(fPartData[1]));

    // save off the partwrapper object

    fSelf = partWrapper;

    // Note the draft permissions, in order to avoid writing to a readonly draft.

    fPermissions = storageUnit->GetDraft(ev)->GetPermissions(ev);

    // Set the dirty flag to false.

    fDirty = kODFalse;

}

Sample Code for Externalization

void    MyPartExternalize(MyPart* somSelf,
                                Environment* ev)

{

    // Only Externalize when the Part has been updated.

    // Externalize the parent.

    parent_Externalize(somSelf, ev);

    if (fDirty) {

        // Get the Part's Storage Unit.

        ODStorageUnit* storageUnit = somSelf->GetStorageUnit(ev);

  if (storageUnit->Exists(ev, kODPropContents, kMyPartKind, 0))
        {
        // Focus to the desired value.

        storageUnit->Focus(ev,
                                kODPropContents,
                                kODPosUndefined,
                                kMyPartKind,
                                0,
                                kODPosUndefined);
        }
        else
        {
            storageUnit->AddProperty(ev, kODPropContents);
            storageUnit->AddValue(ev, kMyPartKind);

            // Adding a property and value has the sideeffect of focusing the storageunit to that value.
        }

        // Write out the Part Data

        storageUnit->SetValue(ev, fPartData[0],&(fPartData[1]));

        // Set the dirty flag to kODFalse to signify that the Part is clean.

        fDirty = kODFalse;

    }

}